IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/impCreateZoom.z/impCreateZoom

Text File | 2002-10-03 | 16.1 KB | 331 lines

iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))



NNNNAAAAMMMMEEEE
     impCreateZoom, impDestroyZoom, impResetZoom, impZoomRow - zoom image data

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<iiiimmmmpppp....hhhh>>>>

     IIIIMMMMPPPPZZZZoooooooommmm**** iiiimmmmppppCCCCrrrreeeeaaaatttteeeeZZZZoooooooommmm((((uuuusssshhhhoooorrrrtttt____tttt ssssrrrrccccXXXXSSSSiiiizzzzeeee,,,, uuuusssshhhhoooorrrrtttt____tttt ssssrrrrccccYYYYSSSSiiiizzzzeeee,,,,
                            uuuusssshhhhoooorrrrtttt____tttt ddddssssttttXXXXSSSSiiiizzzzeeee,,,, uuuusssshhhhoooorrrrtttt____tttt ddddssssttttYYYYSSSSiiiizzzzeeee,,,,
                            lllloooonnnngggg mmmmiiiinnnn,,,, lllloooonnnngggg mmmmaaaaxxxx,,,,
                            IIIIMMMMPPPPRRRReeeeaaaaddddRRRRoooowwwwFFFFuuuunnnncccc rrrreeeeaaaaddddRRRRoooowwwwFFFFuuuunnnncccc,,,,
                            iiiinnnntttt nnnnuuuummmmCCCChhhhaaaannnnnnnneeeellllssss,,,,
                            IIIIMMMMPPPPFFFFiiiilllltttteeeerrrrTTTTyyyyppppeeee ffffiiiilllltttteeeerrrrTTTTyyyyppppeeee,,,,
                            ffffllllooooaaaatttt bbbblllluuuurrrrFFFFaaaaccccttttoooorrrr))));;;;

     vvvvooooiiiidddd iiiimmmmppppDDDDeeeessssttttrrrrooooyyyyZZZZoooooooommmm((((IIIIMMMMPPPPZZZZoooooooommmm ****zzzzoooooooommmm))));;;;

     vvvvooooiiiidddd iiiimmmmppppRRRReeeesssseeeettttZZZZoooooooommmm((((IIIIMMMMPPPPZZZZoooooooommmm ****zzzzoooooooommmm))));;;;

     iiiinnnntttt iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((IIIIMMMMPPPPZZZZoooooooommmm ****zzzzoooooooommmm,,,, sssshhhhoooorrrrtttt ****bbbbuuuuffffffffeeeerrrr,,,,
                    uuuusssshhhhoooorrrrtttt____tttt rrrroooowwww,,,, vvvvooooiiiidddd ****cccclllliiiieeeennnnttttDDDDaaaattttaaaa))));;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The _l_i_b_i_m_p library provides an API for performing image resizing or
     zooming. Images can be zoomed up or down using any of a number of
     resampling methods. The resampling methods divide into two categories.
     The first resampling category is non-filtered zooming (a.k.a. replicative
     zoom, decimation). The second resampling category is filtered zooming
     where a filter of a given shape is applied to the data.  The image
     zooming is performed on a row by row basis using a one pass, two
     dimensional convolution.

     To zoom one or more rows of an image, first create a zoom operator by
     calling _i_m_p_C_r_e_a_t_e_Z_o_o_m. One of the parameters to _i_m_p_C_r_e_a_t_e_Z_o_o_m is a
     pointer to a function that will be called during the zoom to read rows of
     the source image. To obtain zoomed rows call _i_m_p_Z_o_o_m_R_o_w.  When all
     desired zoomed rows have been obtained, call _i_m_p_D_e_s_t_r_o_y_Z_o_o_m to deallocate
     storage held by the zoom operator.

     When filtered zooming is performed a number of contiguous rows of image
     data are cached. Often all rows of a given image channel are zoomed
     followed by all rows of the next channel. Since rows are cached, the
     cache should be flushed when switching between image channels. The
     _i_m_p_R_e_s_e_t_Z_o_o_m function performs this row cache flushing operation.

     The _i_m_p_C_r_e_a_t_e_Z_o_o_m function has the following parameters:

     _s_r_c_X_S_i_z_e, _s_r_c_Y_S_i_z_e
                    Width and height of the source image in pixels.

     _d_s_t_X_S_i_z_e, _d_s_t_Y_S_i_z_e
                    Width and height of the destination (i.e. zoomed) image in
                    pixels.



                                                                        PPPPaaaaggggeeee 1111






iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))



     _m_i_n, _m_a_x       Minimum and maximum intensity values to be used for
                    clamping of the zoomed image data. Using certain filters
                    (e.g. Mitchell) it is possible for the zoomed data
                    intensity range to exceed the original data intensity
                    range. Typically these parameters are set to the minimum
                    and maximum possible input data intensities. For example,
                    for 8-bit input data _m_i_n would be set to 0 and _m_a_x would
                    be set to 255.

     _r_e_a_d_R_o_w_F_u_n_c    Pointer to a function that will be called to read a row
                    from the source image. The prototype for this function is:

                    int (*IMPReadRowFunc)(short *buffer,
                                          ushort_t row,
                                          void *clientData);

                    The function should read the image row indicated by _r_o_w
                    and place the data in _b_u_f_f_e_r. The storage for _b_u_f_f_e_r is
                    allocated and deallocated by the zoom operator and should
                    not be manipulated by the read row function. _c_l_i_e_n_t_D_a_t_a is
                    a pointer to caller specific information. The caller may
                    specify a pointer to client data when calling the
                    _i_m_p_Z_o_o_m_R_o_w function. That pointer is passed to the read
                    row function.  At the caller's discretion this pointer may
                    be set to NNNNUUUULLLLLLLL. A common use of the client data is to pass
                    a pointer to a structure containing the image structure
                    pointer and the channel number. The read row function must
                    return -1 if it encountered an error while obtaining the
                    row data and must return a value of 0 or greater if the
                    function succeeds.

     _n_u_m_C_h_a_n_n_e_l_s    Specifies the number of channels of image data that are
                    packed on a single row. For example, if each row contains
                    data for only a single channel, then _n_u_m_C_h_a_n_n_e_l_s should be
                    specified as one. However, if each row contains RGB data
                    packed together as RGBRGBRGB..., _n_u_m_C_h_a_n_n_e_l_s should be
                    specified as three.

     _f_i_l_t_e_r_T_y_p_e     Specifies the type of filter to be used for resampling the
                    image during zooming. The filter types available are:


                                    FFFFiiiilllltttteeeerrrr TTTTyyyyppppeeee    CCCCaaaatttteeeeggggoooorrrryyyy
                                    __________________________
                                    IIIIMMMMPPPPIIIImmmmppppuuuullllsssseeee     Replicative
                                    IIIIMMMMPPPPBBBBooooxxxx         Filtered
                                    IIIIMMMMPPPPTTTTrrrriiiiaaaannnngggglllleeee    Filtered
                                    IIIIMMMMPPPPQQQQuuuuaaaaddddrrrraaaattttiiiicccc   Filtered
                                    IIIIMMMMPPPPMMMMiiiittttcccchhhheeeellllllll    Filtered
                                    IIIIMMMMPPPPGGGGaaaauuuussssssssiiiiaaaannnn    Filtered





                                                                        PPPPaaaaggggeeee 2222






iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))



                    Refer to the section entitled _F_i_l_t_e_r _F_u_n_c_t_i_o_n_s below for
                    detailed information on the available filters.

     _b_l_u_r_F_a_c_t_o_r     Specifies a multiplier for the width of the filter. The
                    default blur factor is 1.0. Higher factors increase the
                    amount of blur present in the image.

     The _i_m_p_Z_o_o_m_R_o_w function has the following parameters:

     _z_o_o_m           Pointer to a zoom operator structure obtained from a call
                    to _i_m_p_C_r_e_a_t_e_Z_o_o_m.

     _b_u_f_f_e_r         Caller allocated buffer that will be filled with the
                    zoomed image row data.  The buffer should be allocated to
                    accomodated _d_s_t_X_S_i_z_e * _n_u_m_C_h_a_n_n_e_l_s * _s_i_z_e_o_f(_s_h_o_r_t) bytes.

     _r_o_w            The desired zoomed row. Rows are numbered from 0 through
                    _d_s_t_Y_S_i_z_e - _1.

     _c_l_i_e_n_t_D_a_t_a     Pointer to client data. This pointer is passed to the
                    _r_e_a_d_R_o_w_F_u_n_c. A typical use of this is for passing a
                    pointer to a structure containing the _I_M_P_I_m_a_g_e pointer and
                    the channel number.

   FFFFIIIILLLLTTTTEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
     The resampling filters available for zooming are summarized below. Note
     that the span of the filter (i.e. x range) is expressed in terms of the
     original image not the zoomed image.

          FFFFiiiilllltttteeeerrrr TTTTyyyyppppeeee    FFFFuuuunnnnccccttttiiiioooonnnn                              SSSSppppaaaannnn
          _______________________________________________________________

          IIIIMMMMPPPPIIIImmmmppppuuuullllsssseeee     Not Applicable

          IIIIMMMMPPPPBBBBooooxxxx         f(x) = 0.0                          x < -0.5
                         f(x) = 1.0                      -0.5 <= x < 0.5
                         f(x) = 0.0                          x >= 0.5

          IIIIMMMMPPPPTTTTrrrriiiiaaaannnngggglllleeee    f(x) = 0.0                          x < -1.0
                         f(x) = 1.0+x                    -1.0 <= x < 0.0
                         f(x) = 1.0-x                     0.0 <= x < 1.0
                         f(x) = 0.0                          x >= 1.0

          IIIIMMMMPPPPQQQQuuuuaaaaddddrrrraaaattttiiiicccc   f(x) = 0.0                          x < -1.5
                         f(x) = 0.5*(x+1.5)^2            -1.5 <= x < -0.5
                         f(x) = 0.75-x^2                 -0.5 <= x < 0.5
                         f(x) = 0.5*(x-1.5)^2             0.5 <= x < 1.5
                         f(x) = 0.0                          x >= 1.5

          IIIIMMMMPPPPMMMMiiiittttcccchhhheeeellllllll    b = 1.0/3.0





                                                                        PPPPaaaaggggeeee 3333






iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))



                         c = 1.0/3.0

                         p0 = (6.0-2.0*b)/6.0
                         p2 = (-18.0+12.0*b+6.0*c)/6.0
                         p3 = (12.0-9.0*b-6.0*c)/6.0
                         q0 = (8.0*b+24.0*c)/6.0
                         q1 = (-12.0*b-48.0*c)/6.0
                         q2 = (6.0*b+30.0*c)/6.0
                         q3 = (-b-6.0*c)/6.0

                         f(x) = 0.0                          x < -2.0
                         f(x) = q0-x*(q1-x*(q2-x*q3))    -2.0 <= x < -1.0
                         f(x) = p0+x*x*(p2-x*p3)         -1.0 <= x < 0.0
                         f(x) = p0+x*x*(p2+x*p3)          0.0 <= x < 1.0
                         f(x) = q0+x*(q1+x*(q2+x*q3))     1.0 <= x < 2.0
                         f(x) = 0.0                          x >= 2.0

          IIIIMMMMPPPPGGGGaaaauuuussssssssiiiiaaaannnn    a(x) = 1.0/exp((1.5*x)^2)
                         b(x) = 1.0/exp(1.5^4)
                         f(x) = a(x)-b(x)

RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
     _i_m_p_C_r_e_a_t_e_Z_o_o_m returns a pointer to a zoom operator structure if execution
     was successful. NNNNUUUULLLLLLLL is returned and _I_M_P_e_r_r_n_o is set if an execution
     error has occurred.

     _i_m_p_Z_o_o_m_R_o_w returns 0 if execution was successful. -1 is returned and
     _I_M_P_e_r_r_n_o is set if an execution error occurred.

EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
     In addition to the system error codes defined in _e_r_r_n_o._h, the following
     _l_i_b_i_m_p specific error codes may be returned.

     _i_m_p_C_r_e_a_t_e_Z_o_o_m will fail under the following circumstances.

     IMP_ERR_MEMALLOC         Dynamic memory allocation failed. This indicates
                              an out-of-memory condition.

     _i_m_p_Z_o_o_m_R_o_w will fail under the following circumstances.

     IMP_ERR_READROW          Read row function failed.

NNNNOOOOTTTTEEEESSSS
     1.   The storage for the _I_M_P_Z_o_o_m structure is allocated by the zoom
          operator creation function. This storage is deallocated by the
          _i_m_p_D_e_s_t_r_o_y_Z_o_o_m function.  The caller should not explicitly
          reallocate or deallocate any storage related to the image structure.

     2.   The fields of the _I_M_P_Z_o_o_m structure are private and should not be
          modified by the caller.





                                                                        PPPPaaaaggggeeee 4444






iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     iiiimmmmppppZZZZoooooooommmmRRRRoooowwww((((3333))))



SSSSEEEEEEEE AAAALLLLSSSSOOOO
     libimp(3)





















































                                                                        PPPPaaaaggggeeee 5555